nice_things/cli/OptionsParser.sh

The OptionsParser class implements a parser for CLI options compatible with the POSIX standard and with added support for GNU extensions, like long options and option-argument separated by an equals sign.

One or more short options without option-arguments, followed by at most one short option that takes an option-argument, can be grouped together behind a single - (hyphen-minus) character.

Option-arguments cannot be optional. If an option takes an argument, it is mandatory.

Option-arguments must come in a separate argument, or be separated by an = equals sign. This implementation does not support the historical behavior of accepting an option-argument as part of the same string as the option, without a separator.

Processing of -- (the end of options flag) is done automatically.

Usage examples

# Implement parse function
parse_option() {
	case "$2" in
	-a) option_a=1 ;;
	-l | --long-option) option_l=1 ;;
	-o | --option-with-arg) OptionsParser_has_opt_arg "$1" 1 && option_o=$3 ;;
	-Z) option_Z=1 ;;
	*) abort "Unknown option '${2}'" 2 ;;
	esac
}

# Initialize variables
option_a='' option_l='' option_o='' option_Z=''

# Parse options from positional parameters
options_parser=#{{{ new OptionsParser }}} parse_option "$@"

# Shift options out of positional parameters
OptionsParser_get_count "$options_parser" opt_count
shift "$opt_count"

# Destroy parser object
OptionsParser_destructor "$options_parser"

OptionsParser

Since 0.3.0 · Source

import "{ OptionsParser }" from nice_things/cli/OptionsParser.sh

Synopsis
OptionsParser <&self> <parser_function> [<args>…]

Configuration
–

Description
Constructor for the OptionsParser class. The name of a user-defined parsing function must be passed in as the <parser_function> parameter, followed by the full arguments list that contains the options to parse—usually that will be "$@".

Usually, this constructor function should be invoked with the new macro, which takes care of creating the <&self> reference to the newly created object.

Options
–

Operands

• <&self>: Self reference.
• <parser_function>: Name of the function that will handle the options.
• <args>: The arguments list containing the options to parse.

Stdin
–

Stdout
–

Stderr
–

Exit status

• 0: Successful completion.
• 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

options_parser=#{{{ new OptionsParser }}} parse_option "$@"

OptionsParser_destructor

Since 0.3.0 · Source

import "{ OptionsParser_destructor }" from nice_things/cli/OptionsParser_destructor.sh

Synopsis
OptionsParser_destructor <&self>

Configuration
–

Description
Clear all data associated with the object.

Options
–

Operands
<&self>: Self reference.

Stdin
–

Stdout
–

Stderr
–

Exit status

• 0: Successful completion.
• 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

OptionsParser_destructor "$options_parser"

OptionsParser_get_count

Since 0.3.0 · Source

import "{ OptionsParser_get_count }" from nice_things/cli/OptionsParser_get_count.sh

Synopsis
OptionsParser_get_count <&self> <out_var>

Configuration
–

Description
Get number of arguments processed as options and option-arguments.

This information is useful for shifting the options out of the positional parameters, for processing operands.

Options
–

Operands

• <&self>: Self reference.
• <out_var>: Output variable; the result will be written to this variable.

Stdin
–

Stdout
–

Stderr
–

Exit status

• 0: Successful completion.
• 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

OptionsParser_get_count "$options_parser" opt_count
shift "$opt_count"

OptionsParser_has_opt_arg

Since 0.3.0 · Source

import "{ OptionsParser_has_opt_arg }" from nice_things/cli/OptionsParser_has_opt_arg.sh

Synopsis
OptionsParser_has_opt_arg <&self> [<abort_on_failure>]

Configuration
–

Description
This method should be used only inside the function used as the OptionsParser constructor's <parser_function>, to indicate that the current option being processed requires an option-argument. If the option-argument is missing from the options being processed, status code 1 will be returned.

If <abort_on_failure> is set, this function will abort the process instead of returning on failure, and a message will be printed to log_error informing the user about the missing option-argument.

Options
–

Operands

• <&self>: Self reference.
• <abort_on_failure>: Set to 1 to abort on failure.

Stdin
–

Stdout
–

Stderr
log_error.

Exit status

• 0: Successful completion.
• 1: Missing option-argument.
• 12: Invalid self reference <&self> (abort).

Abort

• Aborts on missing option-argument if <abort_on_failure> is specified.
• Aborts if self reference <&self> is invalid.

Usage examples

parse_option() {
	case "$2" in
	-a) OptionsParser_has_opt_arg "$1" 1 && option_a=$3 ;;
	-b)
		{ OptionsParser_has_opt_arg "$1" && [ -n "${3-}" ] && option_b=$3; } ||
			abort "Invalid option argument ${2} '${3-}'" 2
		;;
	*) abort "Unknown option '${2}'" 2 ;;
	esac
}